docs(releases): De-duplicate release naming docs, and centralize in /product/releases/naming-releases/ #14748
+79
−658
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…product/releases/naming-releases/
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
codeowner-assignment
bot
requested review from
a team
and removed request for
a team
codeowner-assignment
bot
requested review from
a team
and removed request for
chargome and
a team
Bundle ReportChanges will increase total bundle size by 16.75kB (0.07%) ⬆️. This is within the configured threshold ✅ Detailed changes
Affected Assets, Files, and Routes:view changes for bundle: sentry-docs-server-cjsAssets Changed:
view changes for bundle: sentry-docs-client-array-pushAssets Changed:
|
| The value can be arbitrary, but for certain platforms, recommendations exist: | ||
|
|
||
| - for mobile devices use `package-name@version-number` or `package-name@version-number+build-number`. **Do not** use `VERSION_NUMBER (BUILD_NUMBER)` as the parenthesis are used for display purposes (foo@1.0+2 becomes 1.0 (2)), so invoking them will cause an error. | ||
| - if you use a DVCS we recommend using the identifying hash (eg: the commit SHA, `da39a3ee5e6b4b0d3255bfef95601890afd80709`). You can let sentry-cli automatically determine this hash for supported version control systems with `sentry-cli releases propose-version`. |
There was a problem hiding this comment.
this part is not included in the new snippet. is it important to include there?
There was a problem hiding this comment.
i was thinking that it's ok to bury it under "There are some release name restrictions and conventions to be aware of. Learn more about Naming Releases." but i can add it back if that link's easy to miss and the content is more useful to be here up-front.
There was a problem hiding this comment.
I think it's okay to shorten this section, but I would suggest adding a little bit more info in the linked area. I'll add a comment with a suggestion there.
|
|
||
| - for mobile devices use `package-name@version-number` or `package-name@version-number+build-number`. **Do not** use `VERSION_NUMBER (BUILD_NUMBER)` as the parenthesis are used for display purposes (foo@1.0+2 becomes 1.0 (2)), so invoking them will cause an error. | ||
| - if you use a DVCS we recommend using the identifying hash (eg: the commit SHA, `da39a3ee5e6b4b0d3255bfef95601890afd80709`). You can let sentry-cli automatically determine this hash for supported version control systems with `sentry-cli releases propose-version`. | ||
| - if you tag releases we recommend using the release tag prefixed with a product or package name (for example, `my-project-name@2.3.12`). |
|
|
||
| Include a release ID (often called a "version") when you initialize the SDK. | ||
|
|
||
| There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/). |
There was a problem hiding this comment.
should this be inline rather than linked? like the original docs had it
There was a problem hiding this comment.
I think the intention behind this change is to move out non-platform specific content such as naming releases to a central place in our Product docs. 😅
There was a problem hiding this comment.
+1 - I like the idea of centralizing.
Co-authored-by: Michelle Zhang <56095982+michellewzhang@users.noreply.github.com>
Co-authored-by: Michelle Zhang <56095982+michellewzhang@users.noreply.github.com>
jas-kas
approved these changes
Sep 8, 2025
There was a problem hiding this comment.
Nice clean up! A lot less repeated content now 😅
Since we're auditing all these release doc files, the platform docs all being named "Releases & Health" is odd. Shouldn't it be "Release Health"? Or if anything, I'd make it "Releases".
Since this is under the "Configuration" nav item, "Releases" make sense as that is the entity you're configuring. Maybe you can add this bulk change to the PR 👼
|
|
||
| Releases are created directly via [automatic release management](/product/releases/setup/release-automation/), the [Sentry CLI](/cli/releases/), or manually via the [Sentry API](/api/releases/create-a-new-release-for-an-organization/). | ||
|
|
||
| Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. |
There was a problem hiding this comment.
Suggested change
| Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. | |
| Releases can also be auto-created by different systems—for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. |
|
|
||
| ## Release Names | ||
|
|
||
| Release IDs, (often called a "version" or "name") are used to uniquely identify a release across the entire Sentry organization. A release name may be associated with builds, events, sessions, etc. from multiple projects. |
There was a problem hiding this comment.
Suggested change
| Release IDs, (often called a "version" or "name") are used to uniquely identify a release across the entire Sentry organization. A release name may be associated with builds, events, sessions, etc. from multiple projects. | |
| Release IDs (often called a "version" or "name") are used to uniquely identify a release across the entire Sentry organization. A release name may be associated with builds, events, sessions, etc. from multiple projects. |
| </Alert> | ||
|
|
||
| The value can be arbitrary, but there are a few restrictions. In all cases, the release name cannot: | ||
| - contain newlines, tabulator characters, forward slashes(`/`) or back slashes(`\`) |
There was a problem hiding this comment.
Suggested change
| - contain newlines, tabulator characters, forward slashes(`/`) or back slashes(`\`) | |
| - contain newlines, tabulator characters, forward slashes (`/`) or back slashes (`\`) |
| We automatically detect whether a project is using semantic or time-based versioning based on: | ||
|
|
||
| - If ≤ 2 releases total: we look at most recent release. | ||
| - If 3-9 releases (inclusive): if any of the most recent 3 releases is semver, project is semver. |
There was a problem hiding this comment.
Suggested change
| - If 3-9 releases (inclusive): if any of the most recent 3 releases is semver, project is semver. | |
| - If 3-9 releases (inclusive): if any of the most recent 3 releases is semver, project is semver (i.e., semantic versioning). |
|
|
||
| Include a release ID (often called a "version") when you initialize the SDK. | ||
|
|
||
| There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/). |
There was a problem hiding this comment.
Suggested change
| There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/). | |
| There are some release name restrictions and conventions to be aware of. [Learn more about naming releases](/product/releases/naming-releases/). |
|
|
||
| Include a release ID (often called a "version") when you initialize the SDK. | ||
|
|
||
| There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/). |
There was a problem hiding this comment.
I think the intention behind this change is to move out non-platform specific content such as naming releases to a central place in our Product docs. 😅
|
|
||
| There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/). | ||
|
|
||
| Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. |
There was a problem hiding this comment.
This releases link just brings users back to the same exact page they are already on, with the added step of having to select a platform. 🤔 What information do you want to point to here?
|
|
||
| There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/). | ||
|
|
||
| Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. |
There was a problem hiding this comment.
Suggested change
| Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. | |
| Releases can also be auto-created by different systems—for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. |
| ``` | ||
|
|
||
| Releases can also be auto created by different systems. For instance upon uploading a source map a release is automatically created. Likewise releases are created by some clients when an event for a release comes in. | ||
| There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/). |
There was a problem hiding this comment.
Suggested change
| There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/). | |
| There are some release name restrictions and conventions to be aware of. [Learn more about naming releases](/product/releases/naming-releases/). |
There was a problem hiding this comment.
I'm thinking through if I were to land on this page and just want to know the quick and dirty of naming. I like shortening this section, but think this part is still pretty important context, even on this page;
- contain newlines, tabulator characters, forward slashes(/), or back slashes(\)
- be (in their entirety) period (.), double period (..), or space ( )
- exceed 200 characters
There was a problem hiding this comment.
Ohh, looks like we should throw that into the includes file!
| Releases can also be auto created by different systems. For instance upon uploading a source map a release is automatically created. Likewise releases are created by some clients when an event for a release comes in. | ||
| There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/). | ||
|
|
||
| Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. |
There was a problem hiding this comment.
Suggested change
| Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. | |
| Releases can also be auto-created by different systems—for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. |
sfanahata
reviewed
Sep 9, 2025
| - If ≤ 2 releases total: we look at most recent release. | ||
| - If 3-9 releases (inclusive): if any of the most recent 3 releases is semver, project is semver. | ||
| - If 10 or more releases: if any of the most recent 3 releases is semver, and 3 out of the most recent 10 releases is semver, then the project is semver. | ||
| <Include name="bind-release-version.mdx" /> |
sfanahata
reviewed
Sep 9, 2025
|
|
||
| There are some release name restrictions and conventions to be aware of. [Learn more about Naming Releases](/product/releases/naming-releases/). | ||
|
|
||
| Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. |
There was a problem hiding this comment.
Suggested change
| Releases can also be auto-created by different systems -- for instance, upon uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. | |
| Releases can also be auto-created by different systems -- for example, when uploading a source map, or by some clients when an event that is tagged with a release is ingested. Therefore, it's important to set the release name when building and deploying your application. Learn more in our [Releases](/platform-redirect/?next=/configuration/releases/) documentation. |
sfanahata
approved these changes
Sep 9, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I noticed we had a lot of duplicate pages with the same docs related to release names.
The goal of this PR is to:
The new central page is available at:
/product/releases/naming-releases/Some existing pages are now more streamlined and will link to the new central location:
/cli/releases//platforms/javascript/configuration/releases/(19 platform pages with the exact same content)